home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / asg53.zip / ATSAYGET.DOC < prev    next >
Text File  |  1989-12-03  |  14KB  |  299 lines
  1. Documentation for Version 5.3 of the ATSAYGET unit:
  2.  
  3. The new AtSayGet procedures are built around a powerful LINE EDITOR with
  4. WordStar (c) compatibility. These features give the functional equivalence
  5. of the dBase (c) @ Line,Row SAY 'prompt' GET <var> [PICTURE] [RANGE] command.
  6.  
  7. Version 5.3 is smaller, offers a new procedure, insludes an new template code
  8. in the PICTURE clause, and fixes a few minor bugs. As with the previous
  9. version the line editing keys hook into the FULL SCREEN EDITOR available in
  10. the included ReadASG unit.
  11.  
  12.   The AtSayGet unit interface follows:
  13.  
  14. UNIT ATSAYGET;
  15.  
  16. INTERFACE
  17.  
  18. USES
  19.  DOS,
  20.  BlueBag;
  21.  
  22. TYPE
  23.  MaxFL     = 1..20;      {Data field length range for numeric procedures}
  24.  FieldTxt  = STRING[78];
  25.  
  26. CONST
  27.  {ASG exit codes; Inspect ASGExit to see how the procedure exited.}
  28.  Aborted   = -1; {ASG proc would not fit in window. Procedure aborted.}
  29.  Undefined =  0; {you should never get this exit code}
  30.  Tab       =  9; {TAB key was pressed}
  31.  Entered   = 13; {ENTER was pressed or the field filled by the operator}
  32.  ShTab     = 15; {SHIFT TAB keys were pressed}
  33.  Escaped   = 27; {ESC key was pressed}
  34.  Up        = 72; {UP key or ^E was pressed}
  35.  Down      = 80; {DOWN key or ^X was pressed}
  36.  ASGExit   : INTEGER = Undefined;
  37.  SpaceBarOK: BOOLEAN = True; { Space bar (dis)allowed in numeric procedures}
  38.  
  39. VAR        { The following 4 globals are automatically set to appropriate
  40.              values but may be modified in your code. EG: SayAttr:=79 will
  41.              display the prompt as white on red, and GetAttr:=65 will dis-
  42.              play the entry field as blue on red (or underlined on a mono
  43.              screen)    }
  44.  OrgAttr   { Text attribute before entering (and after exiting) an ASG proc}
  45.  SayAttr,  { Text attribute of prompt }
  46.  GetAttr,  { Text attribute of entry field during editing }
  47.  EndAttr,  { Text attribute of entry field after exiting }
  48.            : BYTE;
  49.  
  50. (* BOOLEAN PROCEDURE *)
  51.  
  52. PROCEDURE
  53. AtSayGetBoolean(AtX   :Xrange  ; {X coordinate}
  54.                 AtY   :Yrange  ; {Y coordinate}
  55.                 Say   :FieldTxt; {text of prompt}
  56.             VAR GetB  :BOOLEAN); {Boolean variable;
  57.                                  See comments at end of doc}
  58.  
  59. (* CHARACTOR PROCEDURE  *)
  60.  
  61. PROCEDURE
  62. AtSayGetCharPic(X     :Xrange  ;
  63.                 Y     :Yrange  ;
  64.                 Prompt:FieldTxt; {text of prompt}
  65.             VAR GetC  :CHAR    ; {charactor variable}
  66.                 Pic   :CHAR   ); {(see comments on Pic in 
  67.                                   AtSayGetStrPic below)}
  68.  
  69. (* STRING PROCEDURES *)
  70.  
  71. PROCEDURE
  72. AtSayGetStrLen(AtX   :Xrange  ; {X coordinate}
  73.                AtY   :Yrange  ; {Y coordinate}
  74.                Say   :FieldTxt; {text of prompt}
  75.            VAR GetStr:FieldTxt; {string variable being entered}
  76.                Len   :BYTE   ); {allowed field length of entry}
  77.  
  78. PROCEDURE
  79. AtSayGetStrPic(AtX   :Xrange   ; {X coordinate}
  80.                AtY   :Yrange   ; {Y coordinate}
  81.                Say   :FieldTxt ; {text of prompt}
  82.            VAR GetStr:FieldTxt ; {string variable being entered}
  83.                Pic   :FieldTxt); {picture template}
  84.  
  85.                      {Special PICture charactors:
  86.                       ! converts letters to uppercase
  87.                       # restricts entry to numbers, spaces, signs
  88.                       9 restricts entry to numbers and signs
  89.                       A restricts entry to alphabetic charactors
  90.                       a converts letters to lower case (* NEW W/VER 5.3 *)
  91.                       N restricts entry to letters and numbers
  92.                       X allows any charactor}
  93.  
  94.  
  95. (* NUMERIC PROCEDURES *)
  96.  
  97. PROCEDURE { NEW TO VERSION 5.3 }
  98. AtSayGetByte(AtX   :Xrange  ; {X coordinate}
  99.              AtY   :Yrange  ; {Y coordinate}
  100.              Say   :FieldTxt; {text of prompt}
  101.          VAR GetB  :BYTE    ; {BYTE numeric variable being entered}
  102.              FldLen:MaxFL  ); {Length of entry field. (FldLen>3 is useless)}
  103.  
  104. PROCEDURE
  105. AtSayGetReal(AtX   :Xrange  ; {X coordinate}
  106.              AtY   :Yrange  ; {Y coordinate}
  107.              Say   :FieldTxt; {text of prompt}
  108.          VAR GetR  :REAL    ; {Real numeric variable being entered}
  109.              FldLen:MaxFL   ; {Length of entry field}
  110.              DecPl :INTEGER); {decimal places}
  111.  
  112. PROCEDURE
  113. AtSayGetLongInt(AtX   :Xrange  ; {X coordinate}
  114.                 AtY   :Yrange  ; {Y coordinate}
  115.                 Say   :FieldTxt; {text of prompt}
  116.             VAR GetLI :LONGINT ; {LongInt numeric variable being entered}
  117.                 FldLen:MaxFL  ); {Length of entry field (FldLen>10 is useless)}
  118.  
  119. PROCEDURE
  120. AtSayGetInt(AtX   :Xrange  ; {X coordinate}
  121.             AtY   :Yrange  ; {Y coordinate}
  122.             Say   :FieldTxt; {text of prompt}
  123.         VAR GetInt:INTEGER ; {Integer numeric variable being entered}
  124.             FldLen:MaxFL  ); {Length of entry field. (FldLen>6 is useless)}
  125.  
  126. PROCEDURE
  127. AtSayGetWord(AtX   :Xrange  ; {X coordinate}
  128.              AtY   :Yrange  ; {Y coordinate}
  129.              Say   :FieldTxt; {text of prompt}
  130.          VAR GetW  :WORD    ; {Word numeric variable being entered}
  131.              FldLen:MaxFL  ); {Length of entry field. (FldLen>5 is useless)}
  132.  
  133.  
  134.  
  135. The AtSayGetRange procedures shell around the AtSayGet numeric procedures
  136. (which are but shells around the AtSayGetStrPic string procedure). Using 
  137. the AtSayGetRange procedures let you to specify a minimum and maximum
  138. allowable range of input. There are 4 Range procedures which all follow the
  139. syntax of their corresponding ASG numeric procedures except that they re-
  140. quire two additional parameters: the first is the Minimum allowed range and
  141. the 2nd is the Maximum allowed range.
  142.  
  143. PROCEDURE
  144. AtSayGetRealRange(AtX   :Xrange  ; {X coordinate}
  145.                   AtY   :Yrange  ; {Y coordinate}
  146.                   Say   :FieldTxt; {text of prompt}
  147.               VAR GetR  :REAL    ; {numeric variable being entered}
  148.                   FldLen,          {allowed field length of entry}
  149.                   DecPl :MacFL   ; {decimal places}
  150.                   Min,             {minimum acceptable value}
  151.                   Max   :REAL   ); {maximum acceptable value}
  152.  
  153. PROCEDURE
  154. AtSayGetLongIntRange(AtX   :Xrange  ; {X coordinate}
  155.                      AtY   :Yrange  ; {Y coordinate}
  156.                      Say   :FieldTxt; {text of prompt}
  157.                  VAR GetLI :LONGINT ; {numeric variable being entered}
  158.                      FldLen:MaxFL   ; {allowed field length of entry}
  159.                      Min,             {minimum acceptable value}
  160.                      Max   :LONGINT); {maximum acceptable value}
  161.  
  162. PROCEDURE
  163. AtSayGetIntRange(X     :Xrange  ; {X coordinate}
  164.                  Y     :Yrange  ; {Y coordinate}
  165.                  Prompt:FieldTxt; {text of prompt}
  166.              VAR GetI  :INTEGER ; {numeric variable being entered}
  167.                  FldLen:MaxFL   ; {allowed field length of entry}
  168.                  Min,             {minimum acceptable value}
  169.                  Max   :INTEGER); {minimum acceptable value}
  170.  
  171. PROCEDURE
  172. AtSayGetWordRange(X     :Xrange  ; {X coordinate}
  173.                   Y     :Yrange  ; {Y coordinate}
  174.                   Prompt:FieldTxt; {text of prompt}
  175.               VAR GetW  :WORD    ; {numeric variable being entered}
  176.                   FldLen:MaxFL   ; {allowed field length of entry}
  177.                   Min,             {minimum acceptable value}
  178.                   Max   :WORD   ); {minimum acceptable value}
  179.  
  180.   Finally, the simple AtSay procedure used by all of the above has been in-
  181. terfaced. If you are using the procedures in this unit you might as well use
  182. AtSay rather than GoToXY(x,y); WRITE('Something to say');
  183.  
  184. PROCEDURE AtSay(X     :Xrange   ;
  185.                 Y     :Yrange   ;
  186.                 Prompt:FieldTxt); {Prompt is displayed according to SayAttr}
  187.  
  188. EDITING KEYS
  189.  
  190. When you are positioned in a data field certain keys and combinations
  191. of keys will facilitate editing. If the operator is familiar with dBase or
  192. WordStar (s)he will find that the editing keys noted below are very similar.
  193.  
  194. Key(s)         Function                                           ASGExit
  195. -------------- -------------------------------------------------- -------
  196. <-,   ^S . . . Move cursor one character to the left.                 0
  197. ->,   ^D . . . Move cursor one character to the right.                0
  198. ^ <-, ^A . . . Move cursor one word to the left.                      0
  199. ^ ->, ^F . . . Move cursor one word to the right.                     0
  200. Home, ^Z . . . Move to the start of the field.                        0
  201. End,  ^B . . . Move to the last character in the field.               0
  202. Del,  ^G . . . Delete the character at the cursor position and
  203.                pull over all the characters on the right.             0
  204. ^T . . . . . . Delete word to right and pull over remaining text.     0
  205. ^Y . . . . . . Delete the whole field.                                0
  206. ^R . . . . . . Restore field to its original state before edit.       0
  207. BackSpace  . . Delete the character to the left of the cursor and
  208.                pull over all the characters on the right.             0
  209. Ins,  ^V . . . Toggles insert on/off. Block cursor for insert mode.   0
  210. SpaceBar . . . Move cursor to the right. If insert is off it will
  211.                over-write any characters, otherwise it will push them
  212.                to the right as it moves.                              0
  213. Tab  . . . . . Accepts the field and exits if the entry is valid.     9
  214. Enter  . . . .    "     "    "    "    "    "  "    "    "   "        13
  215. Shift Tab  . .    "     "    "    "    "    "  "    "    "   "        15
  216. Esc  . . . . . Exits procedure abandoning any edits that were made    27
  217. UP,   ^E . . . Accepts the field and exits if the entry is valid.     72
  218. DOWN, ^X . . .    "     "    "    "    "    "  "    "    "   "        80
  219.  
  220.                SPECIAL CONSIDERATIONS:
  221.  
  222. Compiler Settings:
  223.      Programs using the AtSayGet or ASGRange units must be compiled with the
  224. Options/Compiler/Var-string checking as RELAXED, or include the {$V-} 
  225. compiler directive.
  226.  
  227. Initialization of variables:
  228.      All formal variable parameters passed to one of the AtSayGet pro-
  229. cedures should first be properly initialized as the current value of the
  230. variable will be displayed in the data field. For example, if you are using
  231. the AtSayGetStrLen procedure to enter a new STRING[10] variable without 1st
  232. properly initializing the variable with an actual or nul value, 10 "random"
  233. charactors will be displayed in the entry field until a ^Y is issued or the
  234. field is filled with data by the operator.
  235.      Special care must taken with variables passed to the AtSayGetStrPic
  236. procedure to initialize the formal variable with the exact length of spaces
  237. or text equal to SizeOf(GetStr).
  238.      When using an AtSayGet procedure to enter numeric data you will also
  239. wish to initialize the variable. All numerals in the entry field, even if
  240. they are seperated with spaces, will compose the value passed by the
  241. procedure. Thus, in a field the length of 4 the entry [12_0] will be re-
  242. turned as [ 120]. This is different than the way dBase accepts numeric input
  243. (which, in this example, would return [  12] ).
  244.  
  245. Screen considerations:
  246.      Unlike some other line editors the prompts in these AtSayGet procedures
  247. are positioned on the screen in the normal Pascal X,Y (column,row) format. 
  248. The dBase style Y,X (row,column) positioning is fine for dBase programmers 
  249. but we use Pascal and should maintain consistency in conventions.
  250.      All of the AtSayGet procedures work equally well on either a mono or
  251. color display. With a color display the procedures automatically adapt to
  252. the background color and display the prompt and field in an appropriate  
  253. color. The default colors c/b altered by changing the global variables   
  254. SayAttr & GetAttr.
  255.      The AtSayGet string procedures indicate insert mode with a block cursor
  256. and overwrite mode with a normal cursor. Upon exit the cursor is set to the
  257. default state for the type of monitor being used. Thus, if you have entered
  258. an AtSayGet procedure with a modified cursor and you want it the same after
  259. exit ing, you will have to re-modify the cursor in your subsequent code.
  260.      Note that the maximum X-coordinate is 79 and the maximum Y-coordinate
  261. is 25. Nevertheless, these procedures will not wrap on the screen, but 
  262. rather will just exit without doing anything if (X+Length(Prompt)+[field
  263. length]) > 80. Likewise, when an AtSayGet procedure is used in a window 
  264. that is narrower than 80 the procedure will exit without running if it  
  265. would otherwise wrap in the window. In either case ASGExit is set to 
  266. Aborted (-1).
  267.      Finally, you can not USE any of these units with TurboPower's TPCRT
  268. unit because they USE CRT. You may change the USEs to TPCRT and recompile
  269. these units if you wish to use TPCRT, but, of course, source code is re-
  270. quired. Source code of the latest version will be sent to all registered
  271. users.
  272.  
  273. Range checking:
  274.      Numeric range checking routines are incorporated within the AtSayGet
  275. numeric procedures. Thus, if the operator enters a negative number in a
  276. AtSayGetWord field the bell will ring and the message ERROR will be briefly
  277. displayed.
  278.      The RANGE clause of dBase was emulated by writing a shell around the
  279. AtSayGet numeric procedures. With an AtSayGetRange procedure an entry that
  280. is too small will sound the bell, briefly fill the field with <<<<<<<..., 
  281. and reset the field to the minimum allowed range. If the entry is too large
  282. the bell sounds, the field is briefly filled with >>>>>>>..., and the field
  283. reset to the maximum allowed value. The procedure will not exit until a valid
  284. range is entered. If you program an illogical range (EG: 70000,-5 in the
  285. AtSayGetWordRange procedure) a compiler range error or run-time range error
  286. will be generated.
  287.  
  288. Valid AtSayGetBoolean enteries:
  289. Affirmative entries are: '+','t','T','y','Y'
  290. Negative entries are:    '-','f','F','n','N'
  291.  
  292. Demonstration of procedures:
  293.      Compile and run DEMO.PAS to see how the procedures in this unit can
  294. be used. When looking at the code notice how the variables are initialized.
  295.  
  296. *  *  *  *  *  *  *  *  * *  *  *  *  *  *  *  *  * *  *  *  *  *  *  *
  297.  
  298.  
  299.